Skip to content

gh-149050: Fix return type of ConfigParser.items() in documentation#150059

Open
Taeknology wants to merge 2 commits into
python:mainfrom
Taeknology:gh-149050-document-configparser-items-itemsview
Open

gh-149050: Fix return type of ConfigParser.items() in documentation#150059
Taeknology wants to merge 2 commits into
python:mainfrom
Taeknology:gh-149050-document-configparser-items-itemsview

Conversation

@Taeknology
Copy link
Copy Markdown

@Taeknology Taeknology commented May 19, 2026

When ConfigParser.items() is called without a section argument, the
implementation delegates to super().items() (i.e. dict.items()) and
returns a collections.abc.ItemsView, not a list. The docs previously
described both overloads as returning a list, which is only correct
for the second overload (with a section argument).

This PR adjusts the first paragraph of the items() documentation in
Doc/library/configparser.rst to say ItemsView instead of list.
The second paragraph (with-section overload) is unchanged because
that one really does return a list.

Verified locally (against Lib/configparser.py on main)

I isolated cpython/Lib/configparser.py from the working tree and
loaded it with importlib.util to confirm the behaviour on current
main (not just the installed interpreter):

import importlib.util
spec = importlib.util.spec_from_file_location(
    "cpy_configparser",
    "/path/to/cpython/Lib/configparser.py",
)
mod = importlib.util.module_from_spec(spec)
spec.loader.exec_module(mod)

cp = mod.ConfigParser()
cp.read_string("[sec]\nkey=val")
print(type(cp.items()).__name__)        # ItemsView
print(type(cp.items("sec")).__name__)   # list

Result:

no_arg type:  collections.abc.ItemsView
with_arg type: builtins.list
no_arg is collections.abc.ItemsView? True
with_arg is list? True

git log -L:'def items':Lib/configparser.py shows the body of
items() has not been touched since 199507b81a (a docstring-only
rst-markup fix), so this is a long-standing docs/behaviour mismatch
rather than a recent regression.

No code change. No Misc/NEWS.d entry (docs-only).

Fixes #149050

…tion

When called without a section argument, ConfigParser.items() delegates
to dict.items() and returns a collections.abc.ItemsView, not a list.
The docs previously described both overloads as returning a list.
@read-the-docs-community
Copy link
Copy Markdown

read-the-docs-community Bot commented May 19, 2026

Copy link
Copy Markdown
Member

@StanFromIreland StanFromIreland left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also fix the case noted in #149050 (comment) please.

The Mapping Protocol Access bullet about parser.items() in
Doc/library/configparser.rst had the same misleading 'returns a list of
section_name, section_proxy pairs' phrasing as the items() method
description.  The no-argument call actually returns an ItemsView, while
the call with a section argument returns a list.  Mark up both return
types explicitly so that the asymmetry between the two overloads is
clear to readers.
@Taeknology
Copy link
Copy Markdown
Author

Addressed in ab94e2b — also updated the Mapping Protocol Access bullet in Doc/library/configparser.rst so that the no-argument call is documented as returning an :class:~collections.abc.ItemsView and the section-argument call as returning a :class:list, matching the actual behaviour.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

awaiting review docs Documentation in the Doc dir skip news

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

Note that configparser.ConfigParser.items returns a collections.abc.ItemsView in the first overload

2 participants